<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>DbEnv::rep_process_message()</title>
    <link rel="stylesheet" href="apiReference.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB C++ API Reference" />
    <link rel="up" href="rep.html" title="Chapter 11.  Replication Methods" />
    <link rel="prev" href="repget_timeout.html" title="DbEnv::rep_get_timeout()" />
    <link rel="next" href="repclockskew.html" title="DbEnv::rep_set_clockskew()" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 11.2.5.3</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">DbEnv::rep_process_message()</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="repget_timeout.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 11. 
                Replication Methods
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="repclockskew.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="repmessage"></a>DbEnv::rep_process_message()</h2>
          </div>
        </div>
      </div>
      <pre class="programlisting">#include &lt;db_cxx.h&gt;
 
int
DbEnv::rep_process_message(Dbt *control, Dbt *rec, int envid, 
                           DbLsn *ret_lsnp)</pre>
      <p>
         The <code class="methodname">DbEnv::rep_process_message()</code> method processes an incoming
         replication message sent by a member of the replication group to the
         local database environment.
    </p>
      <p>
         The <code class="methodname">DbEnv::rep_process_message()</code> method is not called by most
         replication applications.  It should only be called by Base API applications
         implementing their own network transport layer, explicitly holding
         replication group elections and handling replication messages outside
         of the Replication Manager framework.
    </p>
      <p>
         For implementation reasons, all incoming replication messages must be
         processed using the same <a class="link" href="env.html" title="Chapter 5.  The DbEnv Handle">DbEnv</a>  handle.  It is not
         required that a single thread of control process all messages, only
         that all threads of control processing messages use the same handle.
    </p>
      <p>
        Before calling this method, the enclosing database environment must
        already have been opened by calling the 
        <a class="xref" href="envopen.html" title="DbEnv::open()">DbEnv::open()</a> method and must
        already have been configured to send replication messages by
        calling the <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a> 
        method.
    </p>
      <p>
         The <code class="methodname">DbEnv::rep_process_message()</code> method has additional return
         values:
    </p>
      <div class="itemizedlist">
        <ul type="disc">
          <li>
            <p><a id="repmsg_DB_REP_DUPMASTER"></a>
                 <span class="bold"><strong>DB_REP_DUPMASTER</strong></span>
            </p>
            <p>
                The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                <code class="literal">DB_REP_DUPMASTER</code> if the replication group has more than one
                master. The application should reconfigure itself as a client by calling the 
                <a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a>  method, and then call for an
                election by calling <a class="xref" href="repelect.html" title="DbEnv::rep_elect()">DbEnv::rep_elect()</a>.
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_HOLDELECTION"></a>
                         <span class="bold"><strong>DB_REP_HOLDELECTION</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_HOLDELECTION</code> if an election is needed. The application
                 should call for an election by calling 
                 <a class="xref" href="repelect.html" title="DbEnv::rep_elect()">DbEnv::rep_elect()</a>.
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_IGNORE"></a>
                         <span class="bold"><strong>DB_REP_IGNORE</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_IGNORE</code> if this message cannot be processed. This is an
                 indication that this message is irrelevant to the current replication state (for
                 example, an old message from a previous generation arrives and is processed late).
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_ISPERM"></a>
                         <span class="bold"><strong>DB_REP_ISPERM</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_ISPERM</code> if processing this message results in the
                 processing of records that are permanent. The maximum LSN of the permanent records
                 stored is returned.
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_JOIN_FAILURE"></a>
                         <span class="bold"><strong>DB_REP_JOIN_FAILURE</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_JOIN_FAILURE</code> if a new master has been chosen but the
                 client is unable to synchronize with the new master. This is possibly because the client
                 has turned off automatic internal initialization by setting the
                 <a class="link" href="repconfig.html#config_DB_REP_CONF_AUTOINIT">DB_REP_CONF_AUTOINIT</a> 
                 flag to <code class="literal">0</code>.
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_NEWSITE"></a>
                         <span class="bold"><strong>DB_REP_NEWSITE</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_NEWSITE</code> if the system received contact information from a
                 new environment. The <span class="bold"><strong>rec</strong></span> parameter contains the
                 opaque data specified to the <a class="xref" href="repstart.html" title="DbEnv::rep_start()">DbEnv::rep_start()</a>
                 <span class="bold"><strong>cdata</strong></span> parameter.  The application should
                 take whatever action is needed to establish a communication channel with this new
                 environment.
            </p>
          </li>
          <li>
            <p><a id="repmsg_DB_REP_NOTPERM"></a>
                         <span class="bold"><strong>DB_REP_NOTPERM</strong></span>
                </p>
            <p>
                 The <code class="methodname">DbEnv::rep_process_message()</code> method will return
                 <code class="literal">DB_REP_NOTPERM</code> if a message carrying a 
                 <a class="link" href="reptransport.html#transport_DB_REP_PERMANENT">DB_REP_PERMANENT</a> 
                 flag was processed successfully, but was not written to disk. The LSN of this
                 record is returned.  The application should take whatever action is deemed
                 necessary to retain its recoverability characteristics.
            </p>
          </li>
        </ul>
      </div>
      <p>
         Unless otherwise specified, the <code class="methodname">DbEnv::rep_process_message()</code>
         <span>
            
            <span>
                method either returns a non-zero error value or throws an
                exception that encapsulates a non-zero error value on
                failure, and returns 0 on success.
            </span>
        </span>
    </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp9527384"></a>Parameters</h3>
            </div>
          </div>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp9526736"></a>control</h4>
              </div>
            </div>
          </div>
          <p>
                          The <span class="bold"><strong>control</strong></span> parameter should
                          reference a copy of the <span class="bold"><strong>control</strong></span>
                          parameter specified by Berkeley DB on the sending environment.
See the <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a> method for more information.
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp9541904"></a>rec</h4>
              </div>
            </div>
          </div>
          <p>
                          The <span class="bold"><strong>rec</strong></span> parameter should reference a
                          copy of the <span class="bold"><strong>rec</strong></span> parameter specified
                          by Berkeley DB on the sending environment.
See the <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a> method for more information.
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp9543352"></a>envid</h4>
              </div>
            </div>
          </div>
          <p>
                          The <span class="bold"><strong>envid</strong></span> parameter should contain
                          the local identifier that corresponds to the environment that sent the
                          message to be processed (see <a href="../../programmer_reference/rep_id.html" class="olink">Replication environment IDs</a> for more
                          information).
                     </p>
        </div>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp9546032"></a>ret_lsnp</h4>
              </div>
            </div>
          </div>
          <p>
                         If <code class="methodname">DbEnv::rep_process_message()</code> method returns
                         <code class="literal">DB_REP_NOTPERM</code> then the 
                         <span class="bold"><strong>ret_lsnp</strong></span> parameter will contain the log sequence
                         number of this permanent log message that could not be written to disk.  If
                         <code class="methodname">DbEnv::rep_process_message()</code> method returns
                         <code class="literal">DB_REP_ISPERM</code> then the 
                         <span class="bold"><strong>ret_lsnp</strong></span> parameter will contain largest log
                         sequence number of the permanent records that are now written to disk as a
                         result of processing this message.  In all other cases the value of
                         <span class="bold"><strong>ret_lsnp</strong></span> is undefined.

                     </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp9511800"></a>Errors</h3>
            </div>
          </div>
        </div>
        <p>
            The <code class="methodname">DbEnv::rep_process_message()</code>
            <span>
            
            <span>
                method may fail and throw a <a class="link" href="dbexception.html" title="Chapter 6. The DbException Class">DbException</a> 
                exception, encapsulating one of the following non-zero errors, or return one
                of the following non-zero errors:
            </span>
        </span>
        </p>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="idp9554464"></a>EINVAL</h4>
              </div>
            </div>
          </div>
          <p>
                If the database environment was not already configured to
                communicate with a replication group by a call to
                <a class="xref" href="reptransport.html" title="DbEnv::rep_set_transport()">DbEnv::rep_set_transport()</a>; 
                if the database environment was not already opened;
                if this method is called from a Replication Manager
                application; or if an invalid flag value or parameter
                was specified.
            </p>
        </div>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp9533976"></a>Class</h3>
            </div>
          </div>
        </div>
        <p>
                <a class="link" href="env.html" title="Chapter 5.  The DbEnv Handle">DbEnv</a>  
            </p>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="idp9529376"></a>See Also</h3>
            </div>
          </div>
        </div>
        <p>
                     <a class="xref" href="rep.html#replist" title="Replication and Related Methods">Replication and Related Methods</a> 
                </p>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="repget_timeout.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="rep.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="repclockskew.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">DbEnv::rep_get_timeout() </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> DbEnv::rep_set_clockskew()</td>
        </tr>
      </table>
    </div>
  </body>
</html>
